package com.school.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.school.entity.Student;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;

import java.util.List;
import java.util.Map;

/**
 * 学生信息Mapper接口
 * 
 * @author School Development Team
 * @version 1.0.0
 * @since 2024
 */
@Mapper
public interface StudentMapper extends BaseMapper<Student> {

    /**
     * 分页查询学生信息（包含班级和班主任信息）
     * 
     * @param page 分页参数
     * @param params 查询参数
     * @return 学生信息分页结果
     */
    IPage<Student> selectStudentPage(Page<Student> page, @Param("params") Map<String, Object> params);

    /**
     * 根据学生ID查询学生详细信息（包含班级和班主任信息）
     * 
     * @param studentId 学生ID
     * @return 学生详细信息
     */
    Student selectStudentDetailById(@Param("studentId") String studentId);

    /**
     * 根据班级ID查询学生列表
     * 
     * @param classId 班级ID
     * @return 学生列表
     */
    List<Student> selectStudentsByClassId(@Param("classId") String classId);

    /**
     * 根据身份证号查询学生
     * 
     * @param idCard 身份证号
     * @return 学生信息
     */
    Student selectStudentByIdCard(@Param("idCard") String idCard);

    /**
     * 统计各班级学生数量
     * 
     * @return 班级学生数量统计
     */
    List<Map<String, Object>> countStudentsByClass();

    /**
     * 统计各年级学生数量
     * 
     * @return 年级学生数量统计
     */
    List<Map<String, Object>> countStudentsByGrade();

    /**
     * 统计学生状态分布
     * 
     * @return 学生状态统计
     */
    List<Map<String, Object>> countStudentsByStatus();

    /**
     * 根据监护人电话查询学生列表
     * 
     * @param guardianPhone 监护人电话
     * @return 学生列表
     */
    List<Student> selectStudentsByGuardianPhone(@Param("guardianPhone") String guardianPhone);

    /**
     * 批量更新学生班级
     * 
     * @param studentIds 学生ID列表
     * @param classId 新班级ID
     * @return 更新数量
     */
    int batchUpdateStudentClass(@Param("studentIds") List<String> studentIds, @Param("classId") String classId);

    /**
     * 批量更新学生状态
     * 
     * @param studentIds 学生ID列表
     * @param status 新状态
     * @return 更新数量
     */
    int batchUpdateStudentStatus(@Param("studentIds") List<String> studentIds, @Param("status") String status);

    /**
     * 查询即将毕业的学生（根据入学年份计算）
     * 
     * @param graduationYear 毕业年份
     * @return 即将毕业的学生列表
     */
    List<Student> selectGraduatingStudents(@Param("graduationYear") Integer graduationYear);

    /**
     * 查询新入学的学生（指定时间范围）
     * 
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 新入学学生列表
     */
    List<Student> selectNewEnrollmentStudents(@Param("startDate") String startDate, @Param("endDate") String endDate);

    /**
     * 查询未分班的学生
     * 
     * @return 未分班学生列表
     */
    List<Student> selectStudentsWithoutClass();

    /**
     * 根据年龄范围查询学生
     * 
     * @param minAge 最小年龄
     * @param maxAge 最大年龄
     * @return 学生列表
     */
    List<Student> selectStudentsByAgeRange(@Param("minAge") Integer minAge, @Param("maxAge") Integer maxAge);

    /**
     * 查询学生总数
     * 
     * @return 学生总数
     */
    Long countTotalStudents();

    /**
     * 查询活跃学生数
     * 
     * @return 活跃学生数
     */
    Long countActiveStudents();

    /**
     * 模糊查询学生（姓名、学号、电话）
     * 
     * @param keyword 关键词
     * @return 学生列表
     */
    List<Student> searchStudents(@Param("keyword") String keyword);
}